Voice and style

Not everybody who interacts with Octopus Deploy or reads our words is a native English speaker with a degree in computer science, though many are. To make our communication as widely accessible as possible, we recommend:

Voice

• Use US English spelling.
• Address the reader directly by writing in second person. Imagine you are talking to the reader. i.e., To configure X, you need to do Y.
• Use simple sentence structures to avoid overloading the reader with too much information all at once.
• Avoid overly formal language or an academic style, and use simple, declarative language.
• Avoid slang, colloquialisms, and other terms the reader might not be familiar with.
• Use modern language. Language evolves over time, and terms that were once common have fallen out of use. Be deliberate about the language you choose and where terms have changed, don’t cling to old terms just because.

Style

• Use sentence case for titles and only capitalize words that would normally be capitalized.
• Define technical terms the reader might not be familiar with.
• Try to anticipate the types of problems your reader is trying to solve. In documentation, instead of describing features, explain how the feature can solve the user’s problem.

Related pages:

• Style guide home
• Capitalization
• Working with images
• How we write about what we do
• Republishing to dev.to
• Self editing
• Writing documentation quick start
• Writing for Octopus TL;DR
• Writing tips for the blog